Addresses #13644, #13358 (comment) etc:

Motivation

Mitigate users not realizing they're on the latest version of the docs and attempting to use features that don't exist yet, getting errors, and then filing issues or support requests about it.
To some extent, it is inevitable, but in-line versioning is a mitigation in an effort to help users self-service.

Modifications

• remove warning about using mutexes and semaphores together as that is possible in 3.6 after feat: multiple mutexes and semaphores #13358 -- the warning should only be in earlier versions

• use snippet embeds to directly use examples in the docs without duplication

  • single source-of-truth that is testable, consistent, and more discoverable. also avoids potential mistakes/differences, etc
    • Mentioned this in fix(docs): replace outdated whalesay image with busybox #13429 (comment) and elsewhere, thought this was a good time to start using them
  • no longer need a list of examples on this page as such

• add in-line comments with version specifiers on mutexes and semaphores syntax

• add deprecation comments with version specifiers on mutex and semaphore syntax

• add alternative syntax in comments, as suggested in feat: multiple mutexes and semaphores #13358 (comment)

  • this should make it very hard for users to get wrong, which is the intent

• remove "Legacy" section as this does not match conventions

  • we conventionally don't explicitly describe prior state in the docs and leave that to the older versions of the docs (Versioned documentation #11390)
    • (if we did, we could have "legacy" sections ad infinitum. In the Slack thread, this is also 3., that we do not do and is one of the purposes of versioned docs)
  • users also don't read separate sections like this, they get an error and file an issue before they even reach this section, literally per semaphores error: cannot get LockName for a Sync of Unknown type #13644 et al
  • the in-line comments cover this with more direct examples and as you're reading the example instead of after. this follows "show, don't tell" and style guide on directness.
    • the in-line is also more implicit of a reference to older syntax as opposed to an entire explicit section on it
  • we also conventionally don't describe bugs in the docs; combining mutex with semaphore and it not erroring out but silently ignoring the mutex is a confusing bug.
    • (if we did describe bugs, we could have those ad infinitum in the docs as well)

Verification

make docs passes.

Future Work

1. Use embeds for examples in more places in the docs